Управление агентами и токенами

Административный API используется после подключения агента: чтобы посмотреть учётную запись, изменить права, выпустить новый токен, отозвать старый или полностью отключить доступ.

Для первого подключения предпочтителен сценарий самостоятельного подключения: агент создаёт запрос, владелец подтверждает permissions, а Gigma автоматически создаёт учётную запись и первый токен.

Ручной сценарий нужен, когда владелец заранее готовит подключение или восстанавливает доступ после потери токена.

Два способа создать агента

Способ	Когда использовать	Результат
Самостоятельное подключение	агент умеет вызвать HTTP API и может ждать подтверждения	учётная запись и первый токен создаются через `consume`
Ручное создание	владелец заранее готовит подключение	сначала создаётся учётная запись, затем отдельным запросом выпускается токен

POST /api/agents не выдаёт токен автоматически.

Кто может управлять агентами

Для административных операций используются отдельные permissions:

Permission	Что разрешает
`view-agents`	список и карточка агента
`create-agents`	ручное создание агента
`edit-agents`	изменение и отключение
`manage-agent-tokens`	список, выпуск и отзыв токенов

Токенами может управлять только человек. Backend отклоняет учётную запись агента в manageAgentTokens() независимо от выданных ей permissions.

В рабочем профиле не выдавайте обычному агенту view-agents, create-agents, edit-agents и manage-agent-tokens. Текущий backend технически может разрешить агенту часть операций с учётными записями, если такие права были назначены; не используйте это как штатный сценарий.

Дополнительные ограничения делегирования

Перед изменением, отключением и управлением токенами backend проверяет текущую роль и permissions целевого агента.

Для агента с ролью owner или admin нужны edit-admins либо edit-permissions.
Без edit-permissions сотрудник может управлять только агентом, чьи permissions входят в собственный набор сотрудника.
Проверяется текущий набор агента. Нельзя обойти запрет, отправив update с более слабыми правами.

Все операции ограничены проектом сотрудника. ID агента из другого проекта возвращает 404.

Получить список агентов

Получить агентов проекта

Метод: GET
URL: https://api.gigma.ru/api/agents
Авторизация: Bearer сотрудника с view-agents
Headers: Accept: application/json; Authorization: Bearer {user_token}
Успешный ответ: 200

Метод возвращает учётные записи агентов только текущего проекта. Для серверной интеграции используйте этот ресурсный список.

Параметры запроса

role_id[] (integer[], необязательный) — ID ролей;
branch_id[] (integer[], необязательный) — ID филиалов;
department_id[] (integer[], необязательный) — ID отделов;
is_banned (boolean, необязательный) — состояние блокировки;
date_from (date, необязательный) — дата создания от;
date_to (date, необязательный) — дата создания по;
query (string, необязательный) — поиск по имени или login, от 3 до 255 символов.

Пример запроса

GET /api/agents?is_banned=false&query=order HTTP/1.1
Host: api.gigma.ru
Authorization: Bearer <user_token>
Accept: application/json

Ответ

{
	"agents": [
		{
			"id": 214,
			"code": "12345678901",
			"name": "Order Assistant",
			"login": "agent-order-assistant",
			"role": {
				"id": 14,
				"name": "employee",
				"avatar": null,
				"description": "Сотрудник",
				"created_at": "2024-03-27T07:00:46.000000Z"
			},
			"branch": null,
			"department": null,
			"agent_description": "Читает заказы и готовит сводки",
			"is_agent": true,
			"is_banned": false,
			"creator": {
				"id": 7,
				"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
				"first_name": "Project",
				"last_name": "Owner",
				"middle_name": null,
				"name": "Owner Project"
			},
			"last_activity_at": null,
			"permissions": [
				{
					"id": 91,
					"screen": null,
					"name": "view-orders",
					"description": "Просмотр заказов",
					"created_at": "2026-08-01T08:00:00.000000Z"
				},
				{
					"id": 92,
					"screen": null,
					"name": "view-counterparties",
					"description": "Просмотр контрагентов",
					"created_at": "2026-08-01T08:00:00.000000Z"
				}
			],
			"created_at": "2026-08-22T04:00:00.000000Z",
			"updated_at": "2026-08-22T04:00:00.000000Z"
		}
	],
	"agentsCount": 1
}

Список не использует стандартный pagination wrapper. Для административной таблицы с пагинацией используйте следующий метод.

Получить табличный список агентов

Метод: GET
URL: https://api.gigma.ru/api/tables/agents
Авторизация: Bearer сотрудника с view-agents
Headers: Accept: application/json; Authorization: Bearer {user_token}
Успешный ответ: 200

Метод предназначен для административного интерфейса и возвращает определения колонок вместе с пагинацией.

Параметры запроса

Поддерживаются фильтры ресурсного списка, а также:

page (integer, необязательный) — номер страницы;
per_page (integer, необязательный) — размер страницы.

Пример запроса

GET /api/tables/agents?page=1&per_page=20&is_banned=false HTTP/1.1
Host: api.gigma.ru
Authorization: Bearer <user_token>
Accept: application/json

Ответ

{
	"columns": [
		{
			"id": 1,
			"table_id": 1,
			"order": 0,
			"key": "id",
			"has_icon": 0,
			"text": "№"
		}
	],
	"agents": [
		{
			"id": {
				"icon": null,
				"value": 214,
				"url": "<frontend_url>/agents/list-agents/214"
			},
			"code": "12345678901",
			"name": {
				"icon": null,
				"value": "Order Assistant",
				"url": "<frontend_url>/agents/list-agents/214"
			},
			"branch": null,
			"department": null,
			"role": "Сотрудник",
			"login": "agent-order-assistant",
			"is_banned": false,
			"last_activity_at": "Ожидание входа"
		}
	],
	"pagination": {
		"total": 1,
		"per_page": 20,
		"current_page": 1,
		"last_page": 1,
		"from": 1,
		"to": 1
	}
}

Получить учётную запись агента

Метод: GET
URL: https://api.gigma.ru/api/agents/{agent}
Авторизация: Bearer сотрудника с view-agents
Headers: Accept: application/json; Authorization: Bearer {user_token}
Успешный ответ: 200

Параметры пути

agent (integer, обязательный) — ID агента из списка текущего проекта.

Пример запроса

GET /api/agents/214 HTTP/1.1
Host: api.gigma.ru
Authorization: Bearer <user_token>
Accept: application/json

Ответ

{
	"agent": {
		"id": 214,
		"code": "12345678901",
		"name": "Order Assistant",
		"login": "agent-order-assistant",
		"role": {
			"id": 14,
			"name": "employee",
			"avatar": null,
			"description": "Сотрудник",
			"created_at": "2024-03-27T07:00:46.000000Z"
		},
		"branch": null,
		"department": null,
		"agent_description": "Читает заказы и готовит сводки",
		"is_agent": true,
		"is_banned": false,
		"creator": {
			"id": 7,
			"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
			"first_name": "Project",
			"last_name": "Owner",
			"middle_name": null,
			"name": "Owner Project"
		},
		"last_activity_at": null,
		"permissions": [
			{
				"id": 91,
				"screen": null,
				"name": "view-orders",
				"description": "Просмотр заказов",
				"created_at": "2026-08-01T08:00:00.000000Z"
			},
			{
				"id": 92,
				"screen": null,
				"name": "view-counterparties",
				"description": "Просмотр контрагентов",
				"created_at": "2026-08-01T08:00:00.000000Z"
			}
		],
		"created_at": "2026-08-22T04:00:00.000000Z",
		"updated_at": "2026-08-22T04:00:00.000000Z"
	}
}

Ошибки

403 — нет view-agents;
404 — ID не существует, относится к человеку или находится в другом проекте.

Не перебирайте соседние ID после 404.

Создать агента вручную

Создать учётную запись агента

Метод: POST
URL: https://api.gigma.ru/api/agents
Авторизация: Bearer сотрудника с create-agents и правом назначить выбранные роль и permissions
Headers: Accept: application/json; Content-Type: application/json; Authorization: Bearer {user_token}
Успешный ответ: 200

Параметры запроса

name (string, обязательный) — имя агента, от 1 до 255 символов;
login (string, обязательный) — уникальный login, от 3 до 255 символов;
role_id (integer, обязательный) — роль текущего проекта;
branch_id (integer, необязательный) — филиал текущего проекта или null;
department_id (integer, необязательный) — отдел текущего проекта или null;
permissions (string[], необязательный) — permissions с guard_name = user, которые сотрудник может делегировать;
agent_description (string, необязательный) — назначение агента, до 5000 символов, или null;
is_banned (boolean, необязательный) — создать учётную запись сразу отключённой.

project_id, creator_id, code и is_agent назначает backend.

Пример запроса

{
	"name": "Order Assistant",
	"login": "agent-order-assistant",
	"role_id": 14,
	"branch_id": null,
	"department_id": null,
	"permissions": [
		"view-orders",
		"view-counterparties"
	],
	"agent_description": "Читает заказы и готовит сводки",
	"is_banned": false
}

Ответ

{
	"agent": {
		"id": 214,
		"code": "12345678901",
		"name": "Order Assistant",
		"login": "agent-order-assistant",
		"role": {
			"id": 14,
			"name": "employee",
			"avatar": null,
			"description": "Сотрудник",
			"created_at": "2024-03-27T07:00:46.000000Z"
		},
		"branch": null,
		"department": null,
		"agent_description": "Читает заказы и готовит сводки",
		"is_agent": true,
		"is_banned": false,
		"creator": {
			"id": 7,
			"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
			"first_name": "Project",
			"last_name": "Owner",
			"middle_name": null,
			"name": "Owner Project"
		},
		"last_activity_at": null,
		"permissions": [
			{
				"id": 91,
				"screen": null,
				"name": "view-orders",
				"description": "Просмотр заказов",
				"created_at": "2026-08-01T08:00:00.000000Z"
			},
			{
				"id": 92,
				"screen": null,
				"name": "view-counterparties",
				"description": "Просмотр контрагентов",
				"created_at": "2026-08-01T08:00:00.000000Z"
			}
		],
		"created_at": "2026-08-22T04:00:00.000000Z",
		"updated_at": "2026-08-22T04:00:00.000000Z"
	}
}

Успешный ответ — 200. Токен не создаётся. Следующим запросом человек вызывает POST /api/agents/{agent}/tokens.

Изменить агента

Изменить учётную запись агента

Метод: PATCH
URL: https://api.gigma.ru/api/agents/{agent}
Авторизация: Bearer сотрудника с edit-agents и правом управлять текущим агентом
Headers: Accept: application/json; Content-Type: application/json; Authorization: Bearer {user_token}
Успешный ответ: 200

Передавайте только изменяемые поля.

Параметры запроса

name (string, необязательный) — новое имя, от 1 до 255 символов;
login (string, необязательный) — новый уникальный login, от 3 до 255 символов;
role_id (integer, необязательный) — роль текущего проекта;
branch_id (integer|null, необязательный) — филиал или null для очистки;
department_id (integer|null, необязательный) — отдел или null для очистки;
permissions (string[]|null, необязательный) — полный новый набор; пустой массив или null очищает permissions;
agent_description (string|null, необязательный) — новое назначение или null;
is_banned (boolean, необязательный) — состояние блокировки.

Если permissions отсутствует, текущий набор сохраняется. Если поле передано, backend полностью синхронизирует permissions.

Пример запроса

{
	"permissions": [
		"view-orders"
	],
	"agent_description": "Читает заказы без данных клиентов"
}

Ответ

{
	"agent": {
		"id": 214,
		"code": "12345678901",
		"name": "Order Assistant",
		"login": "agent-order-assistant",
		"role": {
			"id": 14,
			"name": "employee",
			"avatar": null,
			"description": "Сотрудник",
			"created_at": "2024-03-27T07:00:46.000000Z"
		},
		"branch": null,
		"department": null,
		"agent_description": "Читает заказы без данных клиентов",
		"is_agent": true,
		"is_banned": false,
		"creator": {
			"id": 7,
			"avatar": "https://api.gigma.ru/storage/uploads/default.svg",
			"first_name": "Project",
			"last_name": "Owner",
			"middle_name": null,
			"name": "Owner Project"
		},
		"last_activity_at": null,
		"permissions": [
			{
				"id": 91,
				"screen": null,
				"name": "view-orders",
				"description": "Просмотр заказов",
				"created_at": "2026-08-01T08:00:00.000000Z"
			}
		],
		"created_at": "2026-08-22T04:00:00.000000Z",
		"updated_at": "2026-08-22T04:15:00.000000Z"
	}
}

Если is_banned становится true, backend сразу отзывает все токены. Повторное включение не восстанавливает прежние секреты.

Laravel resource route принимает и PUT, и PATCH. В списке разрешённых методов административного клиента укажите только тот глагол, который реально используете.

Отключить агента

Отключить учётную запись агента

Метод: DELETE
URL: https://api.gigma.ru/api/agents/{agent}
Авторизация: Bearer сотрудника с edit-agents и правом управлять текущим агентом
Headers: Accept: application/json; Authorization: Bearer {user_token}
Успешный ответ: 200

Endpoint не удаляет запись. Он устанавливает is_banned = true и отзывает все токены агента.

Параметры пути

agent (integer, обязательный) — ID агента текущего проекта.

Пример запроса

DELETE /api/agents/214 HTTP/1.1
Host: api.gigma.ru
Authorization: Bearer <user_token>
Accept: application/json

Ответ

{
	"message": "Агент успешно отключён"
}

Чтобы вернуть агента:

отправьте PATCH /api/agents/{agent} с {"is_banned": false};
человеком выпустите новый Agent Token;
передайте новый секрет агентскому серверу;
проверьте GET /api/user.

Управление токенами

Операции ниже требуют Bearer человека с manage-agent-tokens и правом управлять текущим агентом. Agent Token для них всегда получает 403.

Посмотреть токены

Получить список токенов агента

Метод: GET
URL: https://api.gigma.ru/api/agents/{agent}/tokens
Авторизация: Bearer человека с manage-agent-tokens и правом управлять текущим агентом
Headers: Accept: application/json; Authorization: Bearer {user_token}
Успешный ответ: 200

Параметры пути

agent (integer, обязательный) — ID агента текущего проекта.

Пример запроса

GET /api/agents/214/tokens HTTP/1.1
Host: api.gigma.ru
Authorization: Bearer <user_token>
Accept: application/json

Ответ

{
	"agent_tokens": [
		{
			"id": 901,
			"name": "production-agent",
			"created_at": "2026-08-22T04:00:00+00:00",
			"last_used_at": null,
			"expires_at": "2027-02-22T04:00:00+00:00"
		}
	],
	"agentTokensCount": 1
}

Список не содержит value. Уже выпущенный Bearer прочитать повторно нельзя.

Выпустить токен

Выпустить Agent Token

Метод: POST
URL: https://api.gigma.ru/api/agents/{agent}/tokens
Авторизация: Bearer человека с manage-agent-tokens и правом управлять текущим агентом
Headers: Accept: application/json; Content-Type: application/json; Authorization: Bearer {user_token}
Успешный ответ: 201

Параметры запроса

name (string, обязательный) — назначение токена, от 3 до 100 символов;
expires_at (date-time, необязательный) — срок в будущем, не дальше одного года.

Если expires_at не передан, backend устанавливает срок один год. Отключённому агенту токен не выдаётся.

Пример запроса

{
	"name": "production-agent",
	"expires_at": "2027-02-22T04:00:00+00:00"
}

Ответ

{
	"agent_token": {
		"id": 902,
		"name": "production-agent",
		"created_at": "2026-08-22T04:20:00+00:00",
		"last_used_at": null,
		"expires_at": "2027-02-22T04:00:00+00:00",
		"value": "<agent_bearer>"
	}
}

value показывается только один раз. Сохраните его в хранилище секретов до завершения операции.

Sanctum abilities токена равны *, но бизнес-доступ всё равно определяется ролью и permissions учётной записи агента.

Отозвать токен

Отозвать Agent Token

Метод: DELETE
URL: https://api.gigma.ru/api/agents/{agent}/tokens/{token}
Авторизация: Bearer человека с manage-agent-tokens и правом управлять текущим агентом
Headers: Accept: application/json; Authorization: Bearer {user_token}
Успешный ответ: 200

Параметры пути

agent (integer, обязательный) — ID агента текущего проекта;
token (integer, обязательный) — ID из списка токенов.

Пример запроса

DELETE /api/agents/214/tokens/901 HTTP/1.1
Host: api.gigma.ru
Authorization: Bearer <user_token>
Accept: application/json

Ответ

{
	"message": "Токен агента успешно отозван"
}

Backend ищет токен только внутри выбранного агента. ID токена другой учётной записи возвращает 404.

Ротация токена без простоя

Выпустите новый токен с понятным именем.
Сразу сохраните value.
Настройте агентский сервер на новый секрет.
Выполните GET /api/user.
Выполните безопасный запрос чтения из рабочего профиля.
Отзовите старый токен по его ID.

Не отзывайте старый токен до проверки нового. Разные токены одной учётной записи агента используют одинаковые роль и permissions.

Границы административного API

/api/users* не используется для учётных записей агентов;
DELETE /api/agents/{agent} отключает, а не удаляет запись;
все agent endpoints проверяют проект целевого агента;
значение Agent Token нельзя восстановить или прочитать повторно;
блокировка агента отзывает все его токены;
permissions меняются на учётной записи и сразу влияют на все её токены;
управление токенами выполняет только человек.

Для настройки рабочих инструментов вернитесь в раздел Агентский доступ.

Управление агентами и токенами

Два способа создать агента

Кто может управлять агентами

Дополнительные ограничения делегирования

Рекомендуемый порядок

Получить список агентов

Параметры запроса

Пример запроса

Ответ

Параметры запроса

Пример запроса

Ответ

Получить учётную запись агента

Параметры пути

Пример запроса

Ответ

Ошибки

Создать агента вручную

Параметры запроса

Пример запроса

Ответ

Изменить агента

Параметры запроса

Пример запроса

Ответ

Отключить агента

Параметры пути

Пример запроса

Ответ

Управление токенами

Посмотреть токены

Параметры пути

Пример запроса

Ответ

Выпустить токен

Параметры запроса

Пример запроса

Ответ

Отозвать токен

Параметры пути

Пример запроса

Ответ

Ротация токена без простоя

Границы административного API